package com.xrui.hbase;

import java.io.IOException;

/**
 * Interface for table reader factories.
 * <p>
 * <p> Use <code>Table.getReaderFactory()</code> to create a reader.
 */
public interface ReaderFactory {

    /**
     * Get the table from which readers built by this factory will read.
     *
     * @return the table from which readers built by this factory will read.
     */
    Table getTable();

    /**
     * Opens a new reader for the Table associated with this reader factory.
     * <p>
     * <p>
     * This method is equivalent of <code>readerBuilder().build()</code>. It sets all options to
     * their default values.
     * </p>
     * <p>
     * <p> The caller of this method is responsible for closing the reader. </p>
     * <p>
     * The reader returned by this method does not provide any isolation guarantee.
     * In particular, you should assume that the underlying resources (connections, buffers, etc)
     * are used concurrently for other purposes.
     * </p>
     *
     * @return a new TableReader.
     * @throws IOException on I/O error.
     */
    TableReader openTableReader() throws IOException;

    /**
     * Get a new TableReaderBuilder which builds readers for the table associated with this
     * factory.
     * <p>
     * <p>
     * The reader builder provides several options for setting the behavior of a table reader.
     * <ul>
     * <li>
     * OnDecoderCacheMiss allows setting the reader's behavior when no cell decoder is found in
     * the reader's cache for a particular read request. This may happen if a user specifies a
     * ColumnReaderSpec as an override in a DataRequest without having specified that
     * ColumnReaderSpec during construction of the reader. This option defaults to
     * BUILD_AND_CACHE which causes the reader to build new cell decoders for overrides from
     * data requests and store them in its cache to serve future requests.
     * </li>
     * <li>
     * ColumnReaderSpec overrides allow setting the default read behavior per column. If an
     * override exists for a column, data requests which include that column will be fulfilled
     * according to the specification in the ColumnReaderSpec, even if the data request did not
     * explicitly request the override. If a data request includes a ColumnReaderSpec override
     * different from the override specified during construction of the reader, the data
     * request's override will take precedence. This option defaults to not override any
     * columns.
     * </li>
     * <li>
     * ColumnReaderSpec alternatives instruct the reader to create cell decoders for all
     * specified ColumnReaderSpecs, but not to override the default read behavior. Setting these
     * alternatives can improve performance and will prevent exceptions when using
     * {@link TableReaderBuilder.OnDecoderCacheMiss#FAIL} if the
     * ColumnReaderSpec override in a DataRequest was also specified in the alternatives
     * map during construction of the reader. This option defaults to not include any
     * alternatives.
     * </li>
     * </ul>
     * <p>
     * <p>
     * Readers returned from this builder must be closed when they are no longer needed to release
     * underlying resources.
     * </p>
     *
     * @return a new TableReaderBuilder.
     */
    TableReaderBuilder readerBuilder();
}
